package com.tjetc.service;

import com.tjetc.common.JsonResult;
import com.tjetc.entity.TravelGuide;
import org.springframework.web.multipart.MultipartFile;

/**
 * 旅游攻略服务接口
 * 定义了攻略相关的业务逻辑方法，包括查询、创建、更新、删除攻略及其相关交互
 * 方法返回统一的JsonResult对象，包含操作结果和数据
 */
public interface TravelGuideService {

    /**
     * 根据ID查询攻略详情
     * 此方法会同时增加攻略的浏览量
     *
     * @param id 攻略ID
     * @return 包含攻略对象的JsonResult，如果不存在返回错误信息
     */
    JsonResult findGuideById(Long id);

    /**
     * 获取热门攻略列表
     * 按照浏览量从高到低排序，返回指定数量的攻略
     *
     * @param limit 返回的最大记录数量
     * @return 包含热门攻略列表的JsonResult
     */
    JsonResult getHotGuides(Integer limit);

    /**
     * 根据目的地查询攻略
     * 支持模糊查询，返回目的地名称中包含指定字符串的所有攻略
     *
     * @param destination 目的地名称（全部或部分）
     * @return 包含匹配目的地攻略列表的JsonResult
     */
    JsonResult findByDestination(String destination);

    /**
     * 查询指定作者的所有攻略
     * 返回作者创建的所有攻略，按创建时间排序
     *
     * @param authorId 作者ID
     * @return 包含作者攻略列表的JsonResult
     */
    JsonResult findByAuthor(Long authorId);

    /**
     * 获取被标记为推荐的攻略
     * 返回系统推荐的攻略列表，数量由参数控制
     *
     * @param limit 返回的最大记录数量
     * @return 包含推荐攻略列表的JsonResult
     */
    JsonResult getFeatured(Integer limit);

    /**
     * 获取编辑推荐的攻略
     * 返回被编辑推荐的攻略列表，数量由参数控制
     *
     * @param limit 返回的最大记录数量
     * @return 包含编辑推荐攻略列表的JsonResult
     */
    JsonResult getEditorChoice(Integer limit);

    /**
     * 创建新攻略
     * 设置攻略的初始状态和统计数据，保存到数据库
     *
     * @param guide 攻略对象，包含基本信息和行程数据
     * @return 包含创建结果和攻略信息的JsonResult
     */
    JsonResult createGuide(TravelGuide guide);

    /**
     * 更新攻略信息
     * 更新攻略的内容，同时更新修改时间和编辑次数
     *
     * @param guide 更新后的攻略对象
     * @return 包含更新结果和攻略信息的JsonResult
     */
    JsonResult updateGuide(TravelGuide guide);

    /**
     * 删除攻略
     * 执行逻辑删除，将攻略状态设置为已删除(3)
     *
     * @param id 要删除的攻略ID
     * @return 包含删除结果的JsonResult
     */
    JsonResult deleteGuide(Long id);

    /**
     * 上传攻略封面图片
     * 将图片保存到服务器，并更新攻略的封面图片路径
     *
     * @param file 上传的图片文件
     * @param guideId 攻略ID
     * @return 包含上传结果和图片路径的JsonResult
     */
    JsonResult uploadCoverImage(MultipartFile file, Long guideId);

    /**
     * 增加攻略浏览量
     * 将指定攻略的浏览次数加1
     *
     * @param guideId 攻略ID
     * @return 包含操作结果的JsonResult
     */
    JsonResult incrementView(Long guideId);

    /**
     * 点赞攻略
     * 将指定攻略的点赞次数加1
     *
     * @param guideId 攻略ID
     * @return 包含操作结果的JsonResult
     */
    JsonResult likeGuide(Long guideId);

    /**
     * 收藏攻略
     * 将指定攻略的收藏次数加1
     *
     * @param guideId 攻略ID
     * @return 包含操作结果的JsonResult
     */
    JsonResult favoriteGuide(Long guideId);
}